​
Agents Class

The Agents class is the main entry point for managing multiple agents and their lifecycle within the xpander.ai platform.

​
Constructor

Agents(configuration: Optional[Configuration] = None)
Parameters:
  • configuration ([Configuration](/API reference/configuration), optional): SDK configuration. If not provided, uses environment variables.
Example: 
from xpander_sdk import Agents

# Using default configuration (environment variables)
agents = Agents()

# Using custom configuration
from xpander_sdk import Configuration
config = Configuration(api_key="your-key", organization_id="your-org")
agents = Agents(configuration=config)

​
Methods

​
alist()

Asynchronously retrieve a list of all agents. 
async def alist() -> List[AgentsListItem]
Returns: List of [AgentsListItem](/API reference/agents/API reference/agents-list-item) objects containing agent summaries. Example: 
agents_list = await agents.alist()
for agent in agents_list:
    print(f"Agent: {agent.name} (ID: {agent.id})")
Raises:
  • [ModuleException](/API reference/exceptions): If the request fails or authentication is invalid.

​
list()

Synchronously retrieve a list of all agents. 
def list() -> List[AgentsListItem]
Returns: List of [AgentsListItem](/API reference/agents/API reference/agents-list-item) objects containing agent summaries. Example: 
agents_list = agents.list()
for agent in agents_list:
    print(f"Agent: {agent.name} (ID: {agent.id})")
Raises:
  • [ModuleException](/API reference/exceptions): If the request fails or authentication is invalid.

​
aget(agent_id, version=None)

Asynchronously retrieve a specific agent by ID. 
async def aget(
    agent_id: str, 
    version: Optional[int] = None
) -> Agent
Parameters:
  • agent_id (str): Unique identifier for the agent
  • version (int, optional): Specific version of the agent to retrieve. If not provided, retrieves the latest version.
Returns: Complete [Agent](/API reference/agents/API reference/agent) object with full configuration. Example: 
# Get latest version
agent = await agents.aget("agent-123")
print(f"Agent name: {agent.name}")

# Get specific version
agent_v2 = await agents.aget("agent-123", version=2)
print(f"Agent version: {agent_v2.version}")
Raises:
  • [ModuleException](/API reference/exceptions): If the agent is not found or access is denied.

​
get(agent_id, version=None)

Synchronously retrieve a specific agent by ID. 
def get(
    agent_id: str, 
    version: Optional[int] = None
) -> Agent
Parameters:
  • agent_id (str): Unique identifier for the agent
  • version (int, optional): Specific version of the agent to retrieve. If not provided, retrieves the latest version.
Returns: Complete [Agent](/API reference/agents/API reference/agent) object with full configuration. Example: 
# Get latest version
agent = agents.get("agent-123")
print(f"Agent name: {agent.name}")

# Get specific version
agent_v2 = agents.get("agent-123", version=2)
print(f"Agent version: {agent_v2.version}")
Raises:
  • [ModuleException](/API reference/exceptions): If the agent is not found or access is denied.

​
Usage Examples

​
Complete Agent Management Workflow

from xpander_sdk import Agents
import asyncio

async def manage_agents():
    agents = Agents()
    
    # List all available agents
    agents_list = await agents.alist()
    print(f"Found {len(agents_list)} agents")
    
    # Load first agent if available
    if agents_list:
        agent = await agents_list[0].aload()
        print(f"Loaded agent: {agent.name}")
        
        # Create a task for this agent
        task = await agent.acreate_task(
            prompt="What capabilities do you have?",
            events_streaming=True
        )
        print(f"Created task: {task.id}")

# Run the async function
asyncio.run(manage_agents())

​
Error Handling

from xpander_sdk import Agents
from xpander_sdk.exceptions import ModuleException

async def safe_agent_retrieval():
    agents = Agents()
    
    try:
        agent = await agents.aget("non-existent-agent")
    except ModuleException as e:
        if e.status_code == 404:
            print("Agent not found")
        elif e.status_code == 403:
            print("Access denied to agent")
        else:
            print(f"Error: {e.description}")
  • [Agent](/API reference/agents/API reference/agent): Individual agent with full capabilities
  • [AgentsListItem](/API reference/agents/API reference/agents-list-item): Agent summary from list operations
  • [Configuration](/API reference/configuration): SDK configuration
  • [Tasks Module](/API reference/tasks): Task creation and management
  • [Tools Repository](/API reference/tools): Tool integration and management
  • [Knowledge Bases](/API reference/knowledge): Document management and search
  • [Events Module](/API reference/events): Event-driven programming